This guide will provide examples of how to use almost every method available in nctoolkit. All example will be tested using two datasets. First, a NetCDF dataset of sea surface temperature from 1850 to the present day. Second, a NetCDF file showing... You can get these data files here.
For all examples we will import nctoolkit as follows:
import nctoolkit as nc
wget ftp://ftp.cdc.noaa.gov/Datasets/COBE2/sst.mon.mean.nc
This method can add to a dataset. You can add a constant, another dataset or a NetCDF file. In the case of datasets or NetCDF files the grids etc. must be of the same structure as the original dataset.
We can illustrate this by first converting the SST dataset and converting it from degrees Celsius to Kelvin.
data = nc.open_data("sst.mon.mean.nc")
data.add(273.15)
data.select_timestep(0)
data.plot()
This method will calculate the annual anomaly compared with a baseline. This can be illustrated by first calculating global mean sea surface temperature and then calculating the anomaly compared with a baseline period of 1900-1919, to estimate how much global sea surface temperatures increased since the start of the 20th Century. And we will use a window of 20 years, so that the anomaly derived uses a rolling mean.
data = nc.open_data("sst.mon.mean.nc")
data.spatial_mean()
data.annual_anomaly(baseline=[1900, 1919], window=20)
data.plot()
This method will calculate the maximum value in each available year and for each grid cell of dataset.
data = nc.open_data("sst.mon.mean.nc")
data.annual_max()
This method will calculate the maximum value in each available year and for each grid cell of dataset.
data = nc.open_data("sst.mon.mean.nc")
data.annual_mean()
This method will calculate the minimum value in each available year and for each grid cell of dataset.
data = nc.open_data("sst.mon.mean.nc")
data.annual_min()
This method will calculate the range of values in each available year and for each grid cell of dataset.
data = nc.open_data("sst.mon.mean.nc")
data.annual_range()
data.select_years(2000)
data.plot()
TBC
TBC
This method let's you run a cdo command. CDO commands are generally of the form "cdo {command} infile outfile". cdo_command therefore only requires the command portion of this. If we wanted to run the following CDO command
cdo -timmean -selmon,4 infile outfile
we would do the following:
data = nc.open_data("sst.mon.mean.nc")
data.cdo_command("-timmean -selmon,4")
data.plot()
This method either adds the areas of each grid cell to the dataset or converts the dataset to a new dataset showing only the grid cell areas. If we wanted to see the grid cell areas of the SST dataset, we would do the following:
data = nc.open_data("sst.mon.mean.nc")
data.cell_areas(join=False)
data.plot()
This method will clip a region to a specified longitude and latitude box. For example, if we wanted to clip a dataset to the North Atlantic, we could do this:
data = nc.open_data("sst.mon.mean.nc")
data.clip(lon = [-80, 20], lat = [40, 70])
data.select_timestep(0)
data.plot()
This method let's us compare all variables in a dataset with a constant. If we wanted to identify all regions with sea surface temperature exceeding 20 C in June 2000, we could do the following:
data = nc.open_data("sst.mon.mean.nc")
data.select_years(2000)
data.select_months(6)
data.compare_all(">20")
data.plot()
This method calculates the correlation coefficients between two variables in space for each time step. We can illustrate, in a rather boring way, by working out the spatial correlation coefficient between sea surface temperature in C and K.
data = nc.open_data("sst.mon.mean.nc")
data.mutate({"sst_k":"sst+273.15"})
data.cor_space("sst", "sst_k")
data.plot()
This method calculates the correlation coefficients between two variables in time for each grid cell. We can illustrate, in a rather boring way, by working out the temporal correlation coefficient between sea surface temperature in C and K.
data = nc.open_data("sst.mon.mean.nc")
data.mutate({"sst_k":"sst+273.15"})
data.cor_time("sst", "sst_k")
data.plot()
TBC
TBC
TBC
TBC
TBC
This method will divide a dataset by a constant, or the values in another dataset of NetCDF file. We can illustrate this by dividing a dataset by itself, and finding the resulting values are 1.
data = nc.open_data("sst.mon.mean.nc")
data.select_timestep(0)
data.divide(data)
data.plot()
TBC
TBC
TBC
TBC
This method will invert the vertical levels of a dataset.
This method will set everything outside a specificied longitude/latitude box to NA. The code below illustrates how to mask the North Atlantic in the SST dataset.
data = nc.open_data("sst.mon.mean.nc")
data.select_timestep(0)
data.mask_box(lon = [-80, 20], lat = [40, 70])
data.plot()
This method will calculate the maximum value of all variables in all grid cells. If we wanted to calculate the maximum observed monthly sea surface temperature in the SST dataset we would do the following:
data = nc.open_data("sst.mon.mean.nc")
data.max()
data.plot()
This method will calculate the mean value of all variables in all grid cells. If we wanted to calculate the maximum observed monthly sea surface temperature in the SST dataset we would do the following:
data = nc.open_data("sst.mon.mean.nc")
data.mean()
data.plot()
TBC
TBC
This method will calculate the maximum value of all variables in all grid cells. If we wanted to calculate the maximum observed monthly sea surface temperature in the SST dataset we would do the following:
data = nc.open_data("sst.mon.mean.nc")
data.max()
data.plot()
This method will calculate the mean value of all variables in all grid cells. If we wanted to calculate the mean observed monthly sea surface temperature in the SST dataset we would do the following:
data = nc.open_data("sst.mon.mean.nc")
data.mean()
data.plot()
TBC
TBC
This method will calculate, for each month, the maximum value of each variable over all time steps.
data = nc.open_data("sst.mon.mean.nc")
data.select_years(range(1990, 1999))
data.monthly_max_climatology()
data.select_months(1)
data.plot()
This method will calculate the mean value of each variable in each month of a dataset. Note that this is calculated for each year. See monthly_mean_climatology if you want to calculate a climatological monthly mean.
TBC
This method will calculate the minimum value of each variable in each month of a dataset. Note that this is calculated for each year. See monthly_min_climatology if you want to calculate a climatological monthly minimum.
TBC
TBC
TBC
This method will multiply a dataset by a constant, another dataset or a NetCDF file. If multiplied by a dataset or NetCDF file, the dataset must have the same grid and can only have one variable.
This method can be used to generate new variables using arithmetic expressions. New variables are added to the dataset. The method requires a dictionary, where the key-value pairs are the new variables and expression required to generate it.
If we wanted to add a new variable in the SST dataset showing SST in Kelvin, we could do the following:
data = nc.open_data("sst.mon.mean.nc")
data.mutate({"sst_k":"sst+273.15"})
data = nc.open_data("sst.mon.mean.nc")
data.mutate({"sst_k":"sst*(sst>20)"})
data.plot()
TBC
This method will calculate a given percentile for each variable and grid cell. This will calculate the percentile using all available timesteps.
We can calculate the 75th percentile of sea surface temperature as follows:
data = nc.open_data("sst.mon.mean.nc")
data.percentile(75)
data.plot()
TBC
This method will plot the contents of a dataset. It will either show a map or a time series, depending on the data type. While it should work on at least 90% of NetCDF data, there are some data types that remain incompatible, but will be added to nctoolkit over time.
This method calculates the range for all variables in each grid cell across all steps.
We can calculate the range of sea surface temperatures in the SST dataset as follows:
data = nc.open_data("sst.mon.mean.nc")
data.range()
data.plot()
TBC
TBC
This method will remap a dataset to a new grid. This grid must be either a pandas data frame, an xarray object, a NetCDF file or a single file nctoolkit dataset. We can illustrate this method be regridding the SST dataset to the North Atlantic.
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC
TBC